---
title: Astro 사이트를 Cloudflare에 배포하세요
description: Cloudflare를 사용하여 Astro 사이트를 웹에 배포하는 방법
sidebar:
  label: Cloudflare
type: deploy
logo: cloudflare
supports: ['ssr', 'static']
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro';
import { Steps } from '@astrojs/starlight/components';
import StaticSsrTabs from '~/components/tabs/StaticSsrTabs.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

프런트엔드 정적 자산과 백엔드 API를 포함한 풀스택 애플리케이션뿐만 아니라 요청 시 렌더링되는 사이트까지 [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) 및 [Cloudflare Pages](https://pages.cloudflare.com/)에 배포할 수 있습니다.

이 가이드에는 다음이 포함됩니다.

- [Cloudflare Workers에 배포하는 방법](#cloudflare-workers)
- [Cloudflare Pages에 배포하는 방법](#cloudflare-pages)

:::note

Cloudflare는 새 프로젝트에 Cloudflare Workers를 사용할 것을 권장합니다. Pages를 사용하는 기존 프로젝트의 경우 [Cloudflare 마이그레이션 가이드](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) 및 [호환성 매트릭스](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/#compatibility-matrix)를 참조하세요.

:::

Astro 프로젝트에서 [Cloudflare 런타임을 사용하는 방법](/ko/guides/integrations-guide/cloudflare/)에 대해 더 자세히 알아보세요.
## 전제 조건

시작하려면 다음이 필요합니다.

- Cloudflare 계정. 아직 계정이 없다면 프로세스 중에 무료 Cloudflare 계정을 만들 수 있습니다.

## Cloudflare Workers

### Wrangler를 사용하여 배포하는 방법

<Steps>
1. [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)를 설치합니다.

    ```bash
    npm install wrangler@latest --save-dev
    ```

2. 사이트에서 요청 시 렌더링을 사용하는 경우, [`@astrojs/cloudflare` 어댑터](/ko/guides/integrations-guide/cloudflare/)를 설치합니다.

    이 명령어는 어댑터를 설치하고 `astro.config.mjs` 파일에 필요한 변경 사항을 한 번에 적용합니다.
    
    <PackageManagerTabs>
      <Fragment slot="npm">
      ```sh
      npx astro add cloudflare
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```sh
      pnpm astro add cloudflare
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```sh
      yarn astro add cloudflare
      ```
      </Fragment>
    </PackageManagerTabs>
      
    <ReadMore>[Astro의 요청 시 렌더링](/ko/guides/on-demand-rendering/)에 대해 더 자세히 알아보세요.</ReadMore>

3. [Wrangler 구성 파일](https://developers.cloudflare.com/workers/wrangler/configuration/)을 생성합니다.
    
    `astro add cloudflare` 명령어를 실행하면 이 파일이 자동으로 생성됩니다. 어댑터를 사용하지 않는 경우 직접 생성해야 합니다.

    <StaticSsrTabs>
      <Fragment slot="static">
        ```jsonc title="wrangler.jsonc"
        {
          "name": "my-astro-app",
          "compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
          "assets": {
            "directory": "./dist",
          }
        }
        ```
      </Fragment>
      <Fragment slot="ssr">
        ```jsonc title="wrangler.jsonc"
        {
          "main": "dist/_worker.js/index.js",
          "name": "my-astro-app",
          "compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
          "compatibility_flags": [
            "nodejs_compat",
            "global_fetch_strictly_public"
          ],
          "assets": {
            "binding": "ASSETS",
            "directory": "./dist"
          },
          "observability": {
            "enabled": true
          }
        }
    ```
      </Fragment>
    </StaticSsrTabs>

4. Wrangler를 사용하여 프로젝트를 로컬에서 미리 봅니다.

    ```bash
    npx astro build && npx wrangler dev
    ```

5. `npx wrangler deploy`를 사용하여 배포합니다.

    ```bash
    npx astro build && npx wrangler deploy
    ```
</Steps>

자산이 업로드되면 Wrangler는 사이트를 검사할 수 있는 미리보기 URL을 제공합니다.

<ReadMore>바인딩과 같은 [Cloudflare 런타임 API](/ko/guides/integrations-guide/cloudflare/)를 사용하는 방법에 대해 더 자세히 알아보세요.</ReadMore>

### CI/CD로 배포하는 방법

푸시할 때 사이트를 자동으로 빌드하고 배포하기 위해 [Workers Builds (베타)](https://developers.cloudflare.com/workers/ci-cd/builds/)와 같은 CI/CD 시스템을 사용할 수도 있습니다.

Workers Builds를 사용하는 경우:

<Steps>
1. 위 Wrangler 섹션에서 1-3단계를 따릅니다.

2.  [Cloudflare 대시보드](https://dash.cloudflare.com/)에 로그인하여 `Workers 및 Pages`로 이동합니다. `생성`을 선택합니다.

3. `리포지토리 가져오기`에서 Git 계정을 선택한 다음 Astro 프로젝트가 포함된 리포지토리를 선택합니다.

4. 다음과 같이 프로젝트를 구성합니다.
    - 빌드 명령: `npx astro build`
    - 배포 명령: `npx wrangler deploy`
    
5. `저장 및 배포`를 클릭합니다. 제공된 `workers.dev` 하위 도메인에서 이제 Worker를 미리 볼 수 있습니다.
</Steps>

## Cloudflare Pages

### Wrangler를 사용하여 배포하는 방법

<Steps>
1. [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)를 설치합니다.

      <PackageManagerTabs>
        <Fragment slot="npm">
        ```sh
        npm install wrangler@latest --save-dev
        ```
        </Fragment>
        <Fragment slot="pnpm">
        ```sh
        pnpm add wrangler@latest --save-dev
        ```
        </Fragment>
        <Fragment slot="yarn">
        ```sh
        yarn add wrangler@latest --dev
        ```
        </Fragment>
      </PackageManagerTabs>
    
2. 사이트에서 요청 시 렌더링을 사용하는 경우, [`@astrojs/cloudflare` 어댑터](/ko/guides/integrations-guide/cloudflare/)를 설치합니다.

    이 명령어는 어댑터를 설치하고 `astro.config.mjs` 파일에 필요한 변경 사항을 한 번에 적용합니다.
    
       <PackageManagerTabs>
        <Fragment slot="npm">
        ```sh
        npx astro add cloudflare
        ```
        </Fragment>
        <Fragment slot="pnpm">
        ```sh
        pnpm astro add cloudflare
        ```
        </Fragment>
        <Fragment slot="yarn">
        ```sh
        yarn astro add cloudflare
        ```
        </Fragment>
      </PackageManagerTabs>
      
3. [Wrangler 구성 파일](https://developers.cloudflare.com/workers/wrangler/configuration/)을 생성합니다.
    
    Cloudflare는 신규 프로젝트에 Pages 대신 Workers를 사용할 것을 권장하므로, `astro add cloudflare` 명령은 Workers 프로젝트에 특화된 `wrangler.jsonc` 및 `public/.assetsignore` 파일을 생성합니다. 그래서 `public/.assetsignore` 파일을 삭제하고 `wrangler.jsonc` 파일을 수정해야 합니다. 어댑터를 사용하지 않는다면 직접 생성해야 합니다.
    
    `wrangler.jsonc` 파일이 다음과 같은 구조인지 확인하세요.
    
    <StaticSsrTabs>
      <Fragment slot="static">
      ```jsonc title="wrangler.jsonc"
      {
        "name": "my-astro-app",
        "compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
        "pages_build_output_dir": "./dist"
      }
      ```
      </Fragment>
      <Fragment slot="ssr">
        ```jsonc title="wrangler.jsonc"
        {
          "name": "my-astro-app",
          "compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
          "compatibility_flags": [
            "nodejs_compat",
            "disable_nodejs_process_v2"
          ],
          "pages_build_output_dir": "./dist"
        }
        ```
      </Fragment>
    </StaticSsrTabs>

    <ReadMore>[Astro의 요청 시 렌더링](/ko/guides/on-demand-rendering/)에 대해 더 자세히 알아보세요.</ReadMore>

3. Wrangler를 사용하여 프로젝트를 로컬에서 미리 봅니다.

      <PackageManagerTabs>
        <Fragment slot="npm">
        ```sh
        npx astro build && wrangler pages dev ./dist
        ```
        </Fragment>
        <Fragment slot="pnpm">
        ```sh
        pnpm astro build && wrangler pages dev ./dist
        ```
        </Fragment>
        <Fragment slot="yarn">
        ```sh
        yarn astro build && wrangler pages dev ./dist
        ```
        </Fragment>
      </PackageManagerTabs>

4. `npx wrangler deploy`를 사용하여 배포합니다.

      <PackageManagerTabs>
        <Fragment slot="npm">
        ```sh
        npx astro build && wrangler pages deploy ./dist
        ```
        </Fragment>
        <Fragment slot="pnpm">
        ```sh
        pnpm astro build && wrangler pages deploy ./dist
        ```
        </Fragment>
        <Fragment slot="yarn">
        ```sh
        yarn astro build && wrangler pages deploy ./dist
        ```
        </Fragment>
      </PackageManagerTabs>
</Steps>

자산이 업로드되면 Wrangler는 사이트를 검사할 수 있는 미리보기 URL을 제공합니다.

### CI/CD를 사용하여 사이트를 배포하는 방법

<Steps>
1. 코드를 git 리포지토리 (예: GitHub, GitLab)에 푸시합니다.

2.  [Cloudflare 대시보드](https://dash.cloudflare.com/)에 로그인하여 **컴퓨팅(Workers) > Workers 및 Pages**로 이동합니다. **생성**을 선택하고 **Pages** 탭을 선택합니다. 그리고 git 리포지토리를 연결합니다.

3. 다음과 같이 프로젝트를 구성합니다.
    - **프레임워크 미리 설정**: `Astro`
    - **빌드 명령:** `npm run build`
    - **빌드 출력 디렉터리:** `dist`
    
4. **저장 및 배포** 버튼을 클릭합니다.
</Steps>

## 문제 해결

### 404 동작

Workers 프로젝트에서 사용자 정의 404 페이지를 제공하려면 `not_found_handling`을 설정해야 합니다. Cloudflare 문서의 [라우팅 동작 섹션](https://developers.cloudflare.com/workers/static-assets/#routing-behavior)에서 이에 대해 더 자세히 알아볼 수 있습니다.

```jsonc title="wrangler.jsonc"
{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}
```

Pages 프로젝트에서 사용자 정의 404 페이지를 포함하면 해당 페이지가 기본적으로 제공됩니다. 그렇지 않으면 Pages는 [Cloudflare의 단일 페이지 애플리케이션 렌더링 동작](https://developers.cloudflare.com/pages/configuration/serving-pages/#single-page-application-spa-rendering)을 기본값으로 사용하고 404 페이지를 표시하는 대신 홈 페이지로 리디렉션합니다.

### 클라이언트 측 수화

Cloudflare의 Auto Minify 설정으로 인해 클라이언트 측 하이드레이션이 실패할 수 있습니다. 콘솔에 `Hydration completed but contains mismatches`가 표시되면 Cloudflare 설정에서 Auto Minify를 비활성화하세요.

### Node.js 런타임 API

[Cloudflare 어댑터](/ko/guides/integrations-guide/cloudflare/)와 함께 주문형 렌더링을 사용하는 프로젝트를 빌드한다면 `[Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.`와 같은 오류 메시지와 함께 서버는 빌드에 실패합니다.

- 이는 서버 측 환경에서 사용 중인 패키지 또는 가져오기가 [Cloudflare 런타임 API](https://developers.cloudflare.com/workers/runtime-apis/nodejs/)와 호환되지 않음을 의미합니다.

- Node.js 런타임 API를 직접 가져오는 경우, 해결 방법에 대한 추가 단계는 Cloudflare의 [Node.js 호환성](/ko/guides/integrations-guide/cloudflare/#nodejs-호환성)에 대한 Astro 문서에서 참조할 수 있습니다.

- Node.js 런타임 API를 가져오는 패키지를 가져오는 경우, 패키지 작성자에게 문의하여 `node:*` import 구문을 지원하는지 확인하세요. 그렇지 않은 경우 대체 패키지를 찾아야 할 수도 있습니다.
